Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / cmds.fmt / pmake.man < prev next >

Wrap

Text File | 1991-10-06 | 72KB | 1,653 lines

PMAKE User Commands PMAKE _________________________________________________________________ NNAAMMEE pmake - create programs in parallel SSYYNNOOPPSSIISS ppmmaakkee [--bb] [--dd _w_h_a_t] [--ff _m_a_k_e_f_i_l_e] [--hh] [--ii] [--kk] [--ll] [--nn] [--pp #] [--qq] [--rr] [--ss] [--tt] [--vv] [--xx] [--BB] [--CC] [--DD _v_a_r_i_a_b_l_e] [--II _d_i_r_e_c_t_o_r_y] [--JJ #] [--LL #] [--MM] [--PP] [--RR] [--VV] [--WW] [--XX] [_V_A_R_1==_v_a_l_u_e_1] [_V_A_R_2==_v_a_l_u_e_2......] [_t_a_r_g_1] [_t_a_r_g_2 ...] _________________________________________________________________ -b ``Background'' -- run all remote processes at low priority. See also the .BACKGROUND attribute. -d _w_h_a_t Specify what modules should print debugging information. _w_h_a_t is a string of letters from the fol- lowing set: aa (archives), cc (con- ditionals), dd (directory search- ing), jj (jobs), mm (make), pp (parsing), rr (remote), ss (suf- fixes), tt (targets), vv (vari- ables). Use --dd jjrr to find out what host each job is run on. -f _m_a_k_e_f_i_l_e Specify a different makefile to read than the standard ``Makefile'' or ``makefile''. If _m_a_k_e_f_i_l_e is "-", reads from stan- dard input. -h Prints out help information. -i ``Ignore errors'' -- ignore non- zero exit statuses of commands. -k ``Keepgoing'' -- if an error is encountered, keep working on those parts of the input graph that are not affected by the error. -l PMake has the ability to lock a directory against other people executing it in the same direc- tory (by means of a file called ``LOCK.make'' that it creates and checks for in the directory). This is a Good Thing because two people doing the same thing in Sprite v.1.0 4 February 1991 1 PMAKE User Commands PMAKE the same place can be disastrous for the final product (too many cooks and all that). Whether this locking is the default is up to your system administrator. If locking is on, --ll will turn it off, and vice versa. Note that this locking will not prevent _y_o_u from invoking PMake twice in the same place -- if you own the lock file, PMake will warn you about it but continue to execute. -n ``No execute'' -- do not execute commands. Just print the ones that would be executed. -p # Tell _P_M_a_k_e if and when to print the input graph. The number is the bitwise OR of the numbers 1 and 2 with 1 meaning to print the graph before making anything and 2 meaning to print the graph after making everything. If no number is given, it defaults to 3. -q ``Query'' -- do not execute any commands. Just exit 0 if the given target(s) is (are) up to date and exit non-zero otherwise. -r ``Remove built-in rules'' -- do not parse the built-in rules given in the system makefile. -s ``Silence'' -- do not echo com- mands as they are executed. -t ``Touch targets'' -- rather than executing the commands to create a target, just change its modifi- cation time so it appears up-to- date. This is dangerous. -v ``System V'' -- invokes compati- bility functions suitable for acting like the System V version of Make. This implies -x ``Export judiciously -- run com- mands locally in preference to Sprite v.1.0 4 February 1991 2 PMAKE User Commands PMAKE running them remotely. By default, PMake will only run locally if there are more com- mands to execute than idle hosts available; with this option, PMake will run one command locally and export additional commands to available hosts. --BB ,, and --VV and turns off directory locking. Locking may be turned back on again by giving the --ll flag after --vv .. -B ``Backwards-compatible'' -- per- forms as much like Make as possi- ble (including executing a single shell per command and expanding variables as Make did) while still performing in parallel. -C ``Non-compatible'' -- turns off all compatibility specified up to the point at which --CC is encoun- tered. -D _v_a_r_i_a_b_l_e Defines the given variable to be 11 in the global context. -I _d_i_r_e_c_t_o_r_y Specify another directory in which to look for #include'd makefiles. This flag may be repeated as many times as neces- sary. -J # Specify the maximum number of jobs to run at once on all machines. -L # Specify the maximum number of jobs to run locally. -M Be as much like Make as possible. No parallel execution. Old-style variable expansion. One shell per command. Etc. -P ``Don't use Pipes'' -- see the section on -R ``Remigrate verbosely'' -- announce when processes are remi- grated subsequent to eviction. Sprite v.1.0 4 February 1991 3 PMAKE User Commands PMAKE OOUUTTPPUUTT. -V ``Do old-style variable expan- sion'' -- expands an unknown variable to the empty string. -W Don't print warning messages. -X ``No Export'' -- prohibits expor- tation. VAR=value Set the value of the variable VVAARR to the given value. This super- cedes any value assigned to the variable in the makefile. See VVAARRIIAABBLLEESS. DDEESSCCRRIIPPTTIIOONN _P_M_a_k_e is a program designed to make the maintenance of other programs much easier. Its input is a ``makefile'' that specifies which files depend on which other files and what to do about files that are ``out-of-date.'' If you don't specify a makefile to read, MMaakkeeffiillee and mmaakkeeffiillee, in that order, are looked for and read if they exist. This manual page is meant to be a reference page only. For a more thorough description of _P_M_a_k_e, please refer to _P_M_a_k_e -- _A _T_u_t_o_r_i_a_l(available in this distribution). There are four basic types of lines in a makefile: 1) File dependency specifications 2) Creation commands 3) Variable assignments 4) Comments, include statements and conditional directives Any line may be continued over multiple lines by ending it with a backslash. The backslash, following newline and any initial whitespace on the following line are compressed into a single space. DDEEPPEENNDDEENNCCYY LLIINNEESS On a dependency line, there are targets, sources and an operator. The targets ``depend'' on the sources and are usually created from them. Any number of targets and sources may be specified on a dependency line. All the tar- gets in the line are made to depend on all the sources. If you run out of room, use a backslash at the end of the line Sprite v.1.0 4 February 1991 4 PMAKE User Commands PMAKE to continue onto the next one. Any file may be a target and any file may be a source, but the relationship between them is determined by the ``opera- tor'' that separates them. Three operators are defined: : A target on the line is considered ``out-of-date'' if any of its sources has been modified more recently than the target. Sources for a target accumulate over lines when this operator is used. ! Targets will always be re-created, but this will not happen until all of its sources have been examined and re-created, if necessary. Sources accumulate over lines as for the colon. :: Much like the colon, but acts like the ! operator if no sources are specified. In addition sources do not accumulate over lines. Rather, the commands associated with the line (see below) are executed only if the target is out-of-date with respect to the sources on that line only. In addition, the target will not be removed if _P_M_a_k_e is inter- rupted, unlike for the other two operators. For example: a : a.o b.o c.o b ! d.o e.o c :: f.o command1 a : g.o b ! h.o c :: command2 specifies that a depends on a.o, b.o, c.o and g.o and will be remade only if out-of-date with respect to these four files. b depends on d.o, e.o and h.o and will always be remade, but only after these three files have been remade. c will be remade with command1 if it is out-of-date with respect to f.o, as for the colon operator, while command2 will always be executed. Targets and sources may also contain standard shell wildcard characters (?, *, [ and {}), but the ?, *, [ and ] charac- ters may only be used in the final component of the target or source. If a target or source contains only curly braces and no other wildcard characters, it need not describe an existing file. Otherwise, only existing files will be used. E.g. the pattern {a,b,c}.o will expand to a.o b.o c.o Sprite v.1.0 4 February 1991 5 PMAKE User Commands PMAKE regardless of whether these three files exist, while [abc].o will only expand to this if all three files exist. The resulting expansion is in directory order, not alphabeti- cally sorted as in the shell. CCOOMMMMAANNDDSS Each target has associated with it a sort of shell script made up of a series of shell commands. The creation script for a target should immediately follow the dependency line for that target. Each of the commands in this script _m_u_s_t be preceded by a tab character. While any given target may appear on more than one depen- dency line, only one of these dependency lines may be fol- lowed by a creation script, unless the "::" operator is used. One helpful feature of _P_M_a_k_e is the ability to squirrel away commands for a target to be executed when everything else has been done. To do this, make one of the commands for the target be just ``...'' (an ellipsis) on a line by itself. The ellipsis itself won't be executed, of course, but any commands in the target's script that follow the ellipsis will be saved until _P_M_a_k_e is done processing everything it needs to process. If you were to say, a.o : a.c cc -c a.c ... @echo "All done" Then the command ``echo "All done"'' would execute once everything else had finished. Note that this will only hap- pen if ``a.o'' is found to be out-of-date. There is another way in which makefile shell commands differ from regular shell commands, as illustrated in the above makefile scrap. The first two characters after the initial tab (and any other whitespace) are treated specially. If they are any combination of `@' and `-', (``@'', ``@-'', ``-@'' or ``-''), they cause _P_M_a_k_e to do different things. In most cases, shell commands are printed to the screen before they're actually executed. This is to keep you informed of what's going on. If an `@' appears, however, this echoing is suppressed. In the case of the echo command, above, this makes sense. It would look silly to see echo "All done" All done so _P_M_a_k_e allows you to avoid that (this sort of echo control is only available if you use the Bourne or C shells to exe- cute your commands, since the commands are echoed by the shell, not by _P_M_a_k_e). Sprite v.1.0 4 February 1991 6 PMAKE User Commands PMAKE The other special character is the `-'. Shell commands exit with a certain ``exit status.'' Normally this status will be 0 if everything went ok and non-zero if something went wrong. For this reason, _P_M_a_k_e will consider an error to have occurred if one of the commands it invokes returns a non- zero status. When it detects an error, its usual action is to stop working, wait for everything in process to finish, and exit with a non-zero status itself. This behavior can be altered, however, by means of --ii or --kk arguments, or by placing a `-' at the front of the command. (Another quick note: the decision of whether to abort a target when one of its shell commands returns non-zero is left to the shell that is executing the commands. Some shells allow this ``error-checking'' to be switched on and off at will while others do not.) VVAARRIIAABBLLEESS _P_M_a_k_e has the ability to save text in variables to be recalled later at your convenience. Variables in _P_M_a_k_e are used much like variables in _s_h(1) and, by tradition, consist of all upper-case letters. They are assigned- and appended-to using lines of the form _V_A_R_I_A_B_L_E == _v_a_l_u_e _V_A_R_I_A_B_L_E ++== _v_a_l_u_e respectively, while being conditionally assigned-to (if not already defined) and assigned-to with expansion by lines of the form _V_A_R_I_A_B_L_E ??== _v_a_l_u_e _V_A_R_I_A_B_L_E ::== _v_a_l_u_e Finally, _V_A_R_I_A_B_L_E !!== _c_o_m_m_a_n_d will execute _c_o_m_m_a_n_d using the Bourne shell and place the result in the given variable. Newlines are converted to spaces before the assignment is made. This is not intended to be used with commands that produce a large amount of out- put. If you use it this way, it will probably deadlock. Variables are expanded by enclosing the variable name in either parentheses or curly braces and preceding the whole thing with a dollar sign. E.g. to set the variable CCFFLLAAGGSS to the string ``-I/sprite/src/lib/libc -O'' you would place a line CFLAGS = -I/sprite/src/lib/libc -O in the makefile and use the word $$((CCFFLLAAGGSS)) wherever you would like the string ``-I/sprite/src/lib/libc -O'' to appear. To pass a string of the form ``$(_n_a_m_e)'' or ``${_n_a_m_e}'' through to the shell (e.g. to tell it to substi- tute one of its variables), you can use ``$$(_n_a_m_e)'' and ``$${_n_a_m_e}'', respectively, or, as long as the _n_a_m_e is not a _P_M_a_k_e variable, you can just place the string in directly, as _P_M_a_k_e will not expand a variable it doesn't know, unless it is given one of the three compatibility flags --VV, --BB, or Sprite v.1.0 4 February 1991 7 PMAKE User Commands PMAKE --MM. There are two distinct times at which variable substitution occurs: When parsing a dependency line, such substitution occurs immediately upon reading the line. Thus all vari- ables used in dependency lines must be defined before they appear on any dependency line. For variables that appear in shell commands, variable substitution occurs when the com- mand is processed, i.e. when it is prepared to be passed to the shell or before being squirreled away for later execu- tion (qv. CCOOMMMMAANNDDSS, above). There are four different types of variables at which _P_M_a_k_e will look when trying to expand any given variable. They are (in order of decreasing precedence): (1) variables that are defined specific to a certain target. These are the so- called ``local'' variables and will only be used when per- forming variable substitution on the target's shell script and in dynamic sources (see below for more details), (2) variables that were defined on the command line, (3) vari- ables defined in the makefile and (4) those defined in _P_M_a_k_e's environment, as passed by your login shell. An important side effect of this searching order is that once you define a variable on the command line, nothing in the makefile can change it. _N_o_t_h_i_n_g. As mentioned above, each target has associated with it as many as seven ``local'' variables. Four of these variables are always set for every target that must be re-created. Each local variable has a long, meaningful name and a short, one-character name that exists for backwards-compatibility. They are: @u-3p .TARGET (@) The name of the target. .OODATE (?) The list of sources for this target that were deemed out-of-date. .ALLSRC (>) The list of all sources for this target. .PREFIX (*) The file prefix of the file. This contains only the file portion -- no suffix or leading directory components. Three other ``local'' variables are set only for certain targets under special circumstances. These are the ``.IMPSRC'', ``.ARCHIVE'' and ``.MEMBER'' variables. When they are set, how they are used, and what their short forms Sprite v.1.0 4 February 1991 8 PMAKE User Commands PMAKE are are detailed in later sections. In addition, for you System V fans, the six variables ``@F'', ``@D'', ``<F'', ``<D'', ``*F'', and ``*D'' are defined to be the same as for the System V version of Make. If you don't know about these things, be glad. Four of these local variables may be used in sources on dependency lines. The variables expand to the proper value for each target on the line. The variables are ``.TARGET'', ``.PREFIX'', ``.ARCHIVE'', and ``.MEMBER''. In addition, certain variables are set by or have special meaning to _P_M_a_k_e. The ..PPMMAAKKEE (and MMAAKKEE) variable is set to the name by which _P_M_a_k_e was invoked, to allow recursive makes to use the same version, whatever it may be. All command-line flags given to _P_M_a_k_e are stored in the ..MMAAKKEEFFLLAAGGSS (and MMFFLLAAGGSS) variable just as they were given. This variable is also exported to subshells as the PPMMAAKKEE environment variable. Variable expansion may be modified as for the C shell. A general expansion specification looks like: $$((_v_a_r_i_a_b_l_e[::_m_o_d_i_f_i_e_r[::...]])) Each modifier begins with a single character, thus: M_p_a_t_t_e_r_n This is used to select only those words (a word is a series of characters that are neither spaces nor tabs) that match the given _p_a_t_t_e_r_n . The pattern is a wildcard pattern like that used by the shell, where "*" means 0 or more characters of any sort; "?" is any single character; "[abcd]" matches any single character that is either `a', `b', `c' or `d' (there may be any number of characters between the brackets); [[00--99]] matches any single character that is between `0' and `9' (i.e. any digit. This form may be freely mixed with the other bracket form), and \ is used to escape any of the charac- ters "*", "?", "[" or ":", leaving them as regular characters to match themselves in a word. N_p_a_t_t_e_r_n This is identical to ":M" except it substitutes all words that don't match the given pattern. S/_s_e_a_r_c_h-_s_t_r_i_n_g/_r_e_p_l_a_c_e_m_e_n_t-_s_t_r_i_n_g/[g] Causes the first occurrence of _s_e_a_r_c_h-_s_t_r_i_n_g in the variable to be replaced by _r_e_p_l_a_c_e_m_e_n_t-_s_t_r_i_n_g , unless the "g" flag is given at the end, in which case all occurrences of the string are replaced. The substitution is performed on each Sprite v.1.0 4 February 1991 9 PMAKE User Commands PMAKE word in the variable in turn. If _s_e_a_r_c_h-_s_t_r_i_n_g begins with a "^", the string must match starting at the beginning of the word. If _s_e_a_r_c_h-_s_t_r_i_n_g ends with a "$", the string must match to the end of the word (these two may be combined to force an exact match). If a backslash precedes these two characters, however, they lose their special mean- ing. Variable expansion also occurs in the normal fashion inside both the _s_e_a_r_c_h-_s_t_r_i_n_g and the _r_e_p_l_a_c_e_m_e_n_t-_s_t_r_i_n_g , eexxcceepptt that a backslash is used to prevent the expansion of a "$", not another dollar sign, as is usual. Note that _s_e_a_r_c_h-_s_t_r_i_n_g is just a string, not a pattern, so none of the usual regular-expression/wildcard characters has any special meaning save "^" and "$". In the replacement string, the "&" character is replaced by the _s_e_a_r_c_h-_s_t_r_i_n_g unless it is pre- ceded by a backslash. You are allowed to use any character except colon or exclamation point to separate the two strings. This so-called delimiter character may be placed in either string by preceding it with a backslash. T Replaces each word in the variable expansion by its last component (its ``tail''). H This is similar to ":T", except that every word is replaced by everything but the tail (the ``head''). E ":E" replaces each word by its suffix (``exten- sion''). R This replaces each word by everything but the suf- fix (the ``root'' of the word). In addition, PMake supports the System V form of substitu- tion (_s_t_r_i_n_g_1=_s_t_r_i_n_g_2). CCOOMMMMEENNTTSS,, IINNCCLLUUSSIIOONN AANNDD CCOONNDDIITTIIOONNAALLSS Makefile inclusion and conditional structures reminiscent of the C compiler have also been included in _P_M_a_k_e. Comments begin with a `#' anywhere but in a shell command and continue to the end of the line. If the `#' comes at the beginning of the line, however, the following keywords are recognized and acted on: iinncclluuddee ''''_m_a_k_e_f_i_l_e'''' Sprite v.1.0 4 February 1991 10 PMAKE User Commands PMAKE iinncclluuddee <<_s_y_s_t_e_m _m_a_k_e_f_i_l_e>> This is very similar to the C compiler's file-inclusion facility, right down to the syntax. What follows the ##iinncclluuddee must be a filename enclosed either in double-quotes or angle brackets. Variables will be expanded between the double-quotes or angle-brackets. If angle-brackets are used, the system makefile directory is searched. If the name is enclosed in double-quotes, the including makefile's directory, followed by all directories given via --II argu- ments, followed by the system directory, is searched for a file of the given name. If the file is found, _P_M_a_k_e starts taking input from that file as if it were part of the original makefile. When the end of the file is reached, _P_M_a_k_e goes back to the previous file and continues from where it left off. This facility is recursive up to a depth limited only by the number of open files allowed to any process at one time. iiff [[!!]] _e_x_p_r [[ _o_p _e_x_p_r ...... ]] iiffddeeff [[!!]] _v_a_r_i_a_b_l_e [[_o_p _v_a_r_i_a_b_l_e......]] iiffnnddeeff [[!!]] _v_a_r_i_a_b_l_e [[_o_p _v_a_r_i_a_b_l_e......]] iiffmmaakkee [[!!]] _t_a_r_g_e_t [[_o_p _t_a_r_g_e_t......]] iiffnnmmaakkee [[!!]] _t_a_r_g_e_t [[_o_p _t_a_r_g_e_t......]] These are all the beginnings of conditional constructs in the spirit of the C compiler. Conditionals may be nested to a depth of thirty. In the expressions given above, _o_p may be either |||| (logical OR) or &&&& (logical AND). &&&& has a higher precedence than ||||. As in C, _P_M_a_k_e will evaluate an expression only as far as necessary to determine its value. I.e. if the left side of an &&&& is false, the expression is false and vice versa for ||||. Parentheses may be used as usual to change the order of evaluation. One other boolean operator is provided: !! (logical nega- tion). It is of a higher precedence than either the AND or OR operators, and may be applied in any of the ``if'' con- structs, negating the given function for ``#if'' or the implicit function for the other four. _E_x_p_r can be one of several things. Four functions are pro- vided, each of which takes a different sort of argument. Sprite v.1.0 4 February 1991 11 PMAKE User Commands PMAKE The function ddeeffiinneedd is used to test for the existence of a variable. Its argument is, therefore, a variable name. Certain lower-case variable names (e.g. ``sun'', ``unix'' and ``sprite'') are defined in the system makefile (qv. FFIILLEESS) to specify the sort of system on which _P_M_a_k_e is being run. These are intended to make makefiles more portable. Any variable may be used as the argument of the ddeeffiinneedd function. The mmaakkee function is given the name of a target in the makefile and evaluates to true if the target was given on _P_M_a_k_e's command-line or as a source for the ..MMAAIINN target before the line containing the conditional. The eexxiissttss function takes a file name, which file is searched for on the system search path (as defined by ..PPAATTHH targets (see below)). It evaluates true if the file is found. eemmppttyy takes a variable expansion specification (minus the dollar sign) as its argument. If the resulting expansion is empty, this evaluates true. _E_x_p_r can also be an arithmetic or string comparison, with the lefthand side being a variable expansion. The standard C relational operators are allowed, and the usual number/base conversion is performed, with the exception that octal numbers are not supported. If the righthand side of a "==" or "!=" operator begins with a quotation mark, a string com- parison is done between the expanded variable and the text between the quotation marks. If no relational operator is given, it is assumed that the expanded variable is to be compared against 0, i.e. it is interpreted as a boolean, with a 0 value being false and a non-zero value being true. When, in the course of evaluating one of these conditional expressions, _P_M_a_k_e encounters some word it does not recog- nize, it applies one of either _m_a_k_e or _d_e_f_i_n_e_d to it, depending on the form of ``if'' used. E.g. ``#ifdef'' will apply the _d_e_f_i_n_e_d function, while ``#ifnmake'' will apply the negation of the _m_a_k_e function. If the expression following one of these forms evaluates true, the reading of the makefile continues as before. If it evaluates false, the following lines are skipped. In both cases, this continues until either an ##eellssee or an ##eennddiiff line is encountered. eellssee The #else, as in the C compiler, causes the sense of the last conditional to be inverted and the reading of the Sprite v.1.0 4 February 1991 12 PMAKE User Commands PMAKE makefile to be based on this new value. I.e. if the previ- ous expression evaluated true, the parsing of the makefile is suspended until an #endif line is read. If the previous expression evaluated false, the parsing of the makefile is resumed. eelliiff [[!!]] _e_x_p_r [[ _o_p _e_x_p_r ...... ]] eelliiffddeeff [[!!]] _v_a_r_i_a_b_l_e [[_o_p _v_a_r_i_a_b_l_e......]] eelliiffnnddeeff [[!!]] _v_a_r_i_a_b_l_e [[_o_p _v_a_r_i_a_b_l_e......]] eelliiffmmaakkee [[!!]] _t_a_r_g_e_t [[_o_p _t_a_r_g_e_t......]] eelliiffnnmmaakkee [[!!]] _t_a_r_g_e_t [[_o_p _t_a_r_g_e_t......]] The ``elif'' constructs are a combination of ``else'' and ``if,'' as the name implies. If the preceding ``if'' evaluated false, the expression following the ``elif'' is evaluated and the lines following it are read or ignored the same as for a regular ``if.'' If the preceding ``if'' evaluated true, however, the ``elif'' is ignored and all following lines until the ``endif'' (see below) are ignored. eennddiiff ##eennddiiff is used to end a conditional section. If lines were being skipped, the reading of the makefile resumes. Other- wise, it has no effect (the makefile continues to be parsed as it was just before the ##eennddiiff was encountered). uunnddeeff Takes the next word on the line as a global variable to be undefined (only undefines global variables, not command-line variables). If the variable is already undefined, no message is generated. TTAARRGGEETT AATTTTRRIIBBUUTTEESS In _P_M_a_k_e, files can have certain ``attributes.'' These attributes cause _P_M_a_k_e to treat the targets in special ways. An attribute is a special word given as a source to a target on a dependency line. The words and their functions are given below: .BACKGROUND Forces the target to be run at low priority, to keep it from preventing other higher-priority processes from using idle hosts. .DONTCARE If a target is marked with this attribute and PMake can't figure out how to create it, it will ignore this fact and assume the file isn't Sprite v.1.0 4 February 1991 13 PMAKE User Commands PMAKE really needed or actually exists and PMake just can't find it. .EXEC This causes the marked target's shell script to always be executed (unless the --nn or --tt flag is given), but appear invisible to any targets that depend on it. .EXPORT This is used to mark those targets whose crea- tion should be sent to another machine if at all possible. This may be used by some exporta- tion schemes if the exportation is expensive. You should ask your administrator if it is necessary. .EXPORTSAME Tells the export system that the job should be exported to a machine of the same architecture as the current one. Certain operations (e.g. running text through "nroff") can be performed the same on any architecture (CPU and operating system type), while others (e.g. compiling a program with "cc") must be performed on a machine with the same architecture. Not all export systems will support this attribute. .IGNORE Giving a target the ..IIGGNNOORREE attribute causes PMake to ignore errors from any of the target's commands, as if they all had `-' before them. .INVISIBLE This allows you to specify one target as a source for another without the one affecting the other's local variables. .JOIN This forces the target's shell script to be executed only if one or more of the sources was out-of-date. In addition, the target's name, in both its ..TTAARRGGEETT variable and all the local variables of any target that depends on it, is replaced by the value of its ..AALLLLSSRRCC variable. Another aspect of the .JOIN attribute is it keeps the target from being created if the --tt flag was given. .MAKE The ..MMAAKKEE attribute marks its target as being a recursive invocation of PMake. This forces PMake to execute the script associated with the target (if it's out-of-date) even if you gave the --nn or --tt flag. .NOEXPORT Forces the target to be created locally, even if you've given _P_M_a_k_e the --LL 00 flag. Sprite v.1.0 4 February 1991 14 PMAKE User Commands PMAKE .NOTMAIN Normally, if you do not specify a target to make in any other way, _P_M_a_k_e will take the first target on the first dependency line of a makefile as the target to create. Giving a target this attribute keeps it from this fate. .PRECIOUS When PMake is interrupted, it will attempt to clean up after itself by removing any half-made targets. If a target has this attribute, how- ever, _P_M_a_k_e will leave it alone .SILENT Marking a target with this attribute keeps its commands from being printed when they're exe- cuted. .USE By giving a target this attribute, you turn the target into _P_M_a_k_e's equivalent of a macro. When the target is used as a source for another tar- get, the other target acquires the commands, sources and attributes (except ..UUSSEE) of the source. If the target already has commands, the ..UUSSEE target's commands are added to the end. If more than one .USE-marked source is given to a target, the rules are applied sequentially. SSPPEECCIIAALL TTAARRGGEETTSS As there were in Make, so there are certain targets that have special meaning to PMake. When you use one on a depen- dency line, it is the only target that may appear on the left-hand-side of the operator. The targets are as follows: .BACKGROUND applies the .BACKGROUND attribute to each of its sources. If there are no sources on the depen- dency line, then it is as if you gave PMake the --bb flag. .BEGIN Any commands attached to this target are exe- cuted before anything else is done. You can use it for any initialization that needs doing. .DEFAULT This is sort of a .USE rule for any target (that was used only as a source) that _P_M_a_k_e can't fig- ure out any other way to create. Only the shell script is used. The ..IIMMPPSSRRCC variable of a target that inherits ..DDEEFFAAUULLTT ''ss commands is set to the target's own name. .END This serves a function similar to ..BBEEGGIINN: com- mands attached to it are executed once every- thing has been re-created (so long as no errors occurred). It also serves the extra function of Sprite v.1.0 4 February 1991 15 PMAKE User Commands PMAKE being a place on which PMake can hang commands you put off to the end. Thus the script for this target will be executed before any of the com- mands you save with the ``...''. .EXPORT The sources for this target are passed to the exportation system compiled into _P_M_a_k_e. Some systems will use these sources to configure themselves. You should ask your system adminis- trator about this. .IGNORE This target marks each of its sources with the ..IIGGNNOORREE attribute. If you don't give it any sources, then it is like giving the --ii flag. .INCLUDES The sources for this target are taken to be suf- fixes that indicate a file that can be included in a program source file. The suffix must have already been declared with ..SSUUFFFFIIXXEESS (see below). Any suffix so marked will have the directories on its search path (see ..PPAATTHH ,, below) placed in the ..IINNCCLLUUDDEESS variable, each preceded by a --II flag. The ..hh suffix is already marked in this way in the system makefile. .INTERRUPT When PMake is interrupted, it will execute the commands in the script for this target, if it exists. .LIBS This does for libraries what ..IINNCCLLUUDDEESS does for include files, except the flag used is --LL, as required by those linkers that allow you to tell them where to find libraries. The variable used is ..LLIIBBSS. .MAIN If you didn't give a target (or targets) to create when you invoked PMake, it will take the sources of this target as the targets to create. .MAKEFLAGS This target provides a way for you to always specify flags for PMake when the makefile is used. The flags are just as they would be typed to the shell, though the --ff and --rr flags have no effect. .NULL This allows you to specify what suffix _P_M_a_k_e should pretend a file has if, in fact, it has no known suffix. Only one suffix may be so desig- nated. The last source on the dependency line is the suffix that is used (you should, however, only give one suffix...). Sprite v.1.0 4 February 1991 16 PMAKE User Commands PMAKE .PATH If you give sources for this target, PMake will take them as directories to search for files it cannot find in the current directory. If you give no sources, it will clear out any direc- tories added to the search path before. .PATH_s_u_f_f_i_x This does a similar thing to ..PPAATTHH, but it does it only for files with the given suffix. The suffix must have been defined already. .PRECIOUS Gives the ..PPRREECCIIOOUUSS attribute to each source on the dependency line, unless there are no sources, in which case the ..PPRREECCIIOOUUSS attribute is given to every target in the file. .RECURSIVE Applies the ..MMAAKKEE attribute to all its sources. It does nothing if you don't give it any sources. .SHELL Tells _P_M_a_k_e to use some other shell than the Bourne Shell. The sources for the target are organized as _k_e_y_w_o_r_d==_v_a_l_u_e strings. If a _v_a_l_u_e contains whitespace, it may be surrounded by double-quotes to make it a single word. The pos- sible sources are: ppaatthh==_p_a_t_h Tells where the shell actually resides. If you specify this and nothing else, PMake will use the last component of the path to find the specification. Use this if you just want to use a different version of the Bourne or C Shell (PMake knows how to use the C Shell too). nnaammee==_n_a_m_e This is the name by which the shell is to be known. It is a single word and, if no other keywords are specified (other than ppaatthh), it is the name by which PMake attempts to find a specification for the it. You can use this if you would just rather use the C Shell than the Bourne Shell (``..SSHHEELLLL:: nnaammee==ccsshh'' will do it). qquuiieett==_e_c_h_o-_o_f_f _c_o_m_m_a_n_d The command _P_M_a_k_e should send to stop the shell from printing its commands. Once echoing is off, it is expected to remain off until explicitly turned on. eecchhoo==_e_c_h_o-_o_n _c_o_m_m_a_n_d Sprite v.1.0 4 February 1991 17 PMAKE User Commands PMAKE The command PMake should give to turn echo- ing back on again. ffiilltteerr==_p_r_i_n_t_e_d _e_c_h_o-_o_f_f _c_o_m_m_a_n_d Many shells will echo the echo-off command when it is given. This keyword tells PMake in what format the shell actually prints the echo-off command. Wherever PMake sees this string in the shell's output, it will delete it and any following whitespace, up to and including the next newline. eecchhooFFllaagg==_f_l_a_g _t_o _t_u_r_n _e_c_h_o_i_n_g _o_n The flag to pass to the shell to turn echo- ing on at the start. If either this or the next flag begins with a `-', the flags will be passed to the shell as separate argu- ments. Otherwise, the two will be con- catenated. eerrrrFFllaagg==_f_l_a_g _t_o _t_u_r_n _e_r_r_o_r _c_h_e_c_k_i_n_g _o_n Flag to give the shell to turn error check- ing on at the start. cchheecckk==_c_o_m_m_a_n_d _t_o _t_u_r_n _e_r_r_o_r _c_h_e_c_k_i_n_g _o_n The command to make the shell check for errors or to print the command that's about to be executed (%s indicates where the com- mand to print should go), if hasErrCtl is "no". iiggnnoorree==_c_o_m_m_a_n_d _t_o _t_u_r_n _e_r_r_o_r _c_h_e_c_k_i_n_g _o_f_f The command to turn error checking off or the command to execute a command ignoring any errors. "%s" takes the place of the command. hhaassEErrrrCCttll==_y_e_s _o_r _n_o This takes a value that is either yyeess or nnoo, telling how the "check" and "ignore" commands should be used. NOTE: If this is "no", both the check and ignore commands should contain a \n at their end if the shell requires a newline before executing a command. The strings that follow these keywords may be enclosed in single or double quotes (the quotes will be stripped off) and may contain the usual C backslash-characters. .SILENT Applies the ..SSIILLEENNTT attribute to each of its Sprite v.1.0 4 February 1991 18 PMAKE User Commands PMAKE sources. If there are no sources on the depen- dency line, then it is as if you gave PMake the --ss flag. .SUFFIXES This is used to give new file suffixes for PMake to handle. Each source is a suffix PMake should recognize. If you give a ..SSUUFFFFIIXXEESS dependency line with no sources, PMake will forget about all the suffixes it knew (this also nukes the null suffix). For those targets that need to have suffixes defined, this is how you do it. In addition to these targets, a line of the form _a_t_t_r_i_b_u_t_e : _s_o_u_r_c_e_s applies the _a_t_t_r_i_b_u_t_e to all the targets listed as _s_o_u_r_c_e_s except as noted above. TTHHEE PPOOWWEERR OOFF SSUUFFFFIIXXEESS One of the best aspects of both _M_a_k_e and _P_M_a_k_e comes from their understanding of how the suffix of a file pertains to its contents and their ability to do things with a file based solely on its suffix. _P_M_a_k_e also has the ability to find a file based on its suffix, supporting different types of files being in different directories. The former ability derives from the existence of so-called transformation rules while the latter comes from the specification of search paths using the ..PPAATTHH target. TTRRAANNSSFFOORRMMAATTIIOONN RRUULLEESS A special type of dependency, called a transformation rule, consists of a target made of two known suffixes stuck together followed by a shell script to transform a file of one suffix into a file of the other. The first suffix is the suffix of the source file and the second is that of the target file. E.g. the target ``.c.o,'' followed by com- mands, would define a transformation from files with the ``.c'' suffix to those with the ``.o'' suffix. A transfor- mation rule has no source files associated with it, though attributes may be given to one in the usual way. These attributes are then applied to any target that is on the ``target end'' of a transformation rule. The suffixes that are concatenated must be already known to _P_M_a_k_e in order for their concatenation to be recognized as a transformation, i.e. the suffixes must have been the source for a .SUFFIXES target at some time before the transformation is defined. Many transformations are defined in the system makefile (qv. FFIILLEESS) and I refer you there for more examples as well as to find what is already available (you should especially note the various variables used to contain flags for the com- pilers, assemblers, etc., used to transform the files. These variables allow you to customize the transformations to your Sprite v.1.0 4 February 1991 19 PMAKE User Commands PMAKE own needs without having to redefine them). A transforma- tion rule may be defined more than once, but only the last such definition is remembered by _P_M_a_k_e. This allows you to redefine the transformations in the system makefile if you wish. Transformation rules are used only when a target has no com- mands associated with it, both to find any additional files on which it depends and to attempt to figure out just how to make the target should it end up being out-of-date. When a transformation is found for a target, another of the seven ``local'' variables mentioned earlier is defined: .IMPSRC (<) The name/path of the source from which the target is to be transformed (the ``implied'' source). For example, given the following makefile: a.out : a.o b.o $(CC) $(.ALLSRC) and a directory containing the files a.o, a.c and b.c, _P_M_a_k_e will look at the list of suffixes and transformations given in the built-in rules and find that the suffixes ``.c'' and ``.o'' are both known and there is a transformation rule defined from one to the other with the command ``$(CC) $(CFLAGS) -c $(.IMPSRC).'' Having found this, it can then check the modification times of both a.c and b.c and execute the command from the transformation rule as necessary in order to update the files a.o and b.o. _P_M_a_k_e, unlike _M_a_k_e before it, has the ability to apply several transformations to a file even if the intermediate files do not exist. Given a directory containing a .o file and a .q file, and transformations from .q to .l, .l to .c and .c to .o, _P_M_a_k_e will define a transformation from .q -> .o using the three transformation rules you defined. In the event of two paths between the same suffixes, the shortest path will be chosen between the target and the first exist- ing file on the path. So if there were also a transforma- tion from .l files to .o files, _P_M_a_k_e would use the path .q -> .l -> .o instead of .q -> .l -> .c -> .o. Once an existing file is found, _P_M_a_k_e will continue to look at and record transformations until it comes to a file to which nothing it knows of can be transformed, at which point it will stop looking and use the path it has already found. What happens if you have a .o file, a .q file and a .r file, all with the same prefix, and transformations from .q -> .o and .r -> .o? Which transformation will be used? _P_M_a_k_e uses the order in which the suffixes were given on the ..SSUUFF-- FFIIXXEESS line to decide between transformations: whichever Sprite v.1.0 4 February 1991 20 PMAKE User Commands PMAKE suffix came first, wins. So if the three suffixes were declared .SUFFIXES : .o .q .r the .q -> .o transformation would be applied. Similarly, if they were declared as .SUFFIXES : .o .r .q the .r -> .o transformation would be used. You should keep this in mind when writing such rules. Note also that because the placing of a suffix on a ..SSUUFFFFIIXXEESS line doesn't alter the precedence of previously-defined transformations, it is sometimes necessary to clear the whole lot of them out and start from scratch. This is what the ..SSUUFFFFIIXXEESS-only line, mentioned earlier, will do. SSEEAARRCCHH PPAATTHHSS _P_M_a_k_e also supports the notion of multiple directories in a more flexible, easily-used manner than has been available in the past. You can define a list of directories in which to search for any and all files that aren't in the current directory by giving the directories as sources to the ..PPAATTHH target. The search will only be conducted for those files used only as sources, on the assumption that files used as targets will be created in the current directory. The line .PATH : RCS would tell _P_M_a_k_e to look for any files it is seeking (including ones made up by means of transformation rules) in the RCS directory as well as the current one. Note, however, that this searching is only done if the file is used only as a source in the makefile. I.e. if the file cannot be created by commands in the makefile. A search path specific to files with a given suffix can also be specified in much the same way. .PATH.h : h /sprite/lib/include causes the search for header files to be conducted in the h and /sprite/lib/include directory as well as the current one. When expanding wildcards, these paths are also used. If the pattern has a recognizable suffix, the search path for that suffix is used. Otherwise, the path defined with the regu- lar ..PPAATTHH target is used. When a file is found somewhere other than the current direc- tory, its name is replaced by its full pathname in any ``local'' variables. Two types of suffixes are given special attention when a search path is defined for them. On most systems, the C com- piler lets you specify where to find header files (.h files) Sprite v.1.0 4 February 1991 21 PMAKE User Commands PMAKE by means of --II flags similar to those used by _P_M_a_k_e. If a search path is given for any suffix used as a source for the ..IINNCCLLUUDDEESS target, the variable $$((..IINNCCLLUUDDEESS)) will be set to contain all the directories on the path, in the order given, in a format which can be passed directly to the C compiler. Similarly, on some systems, one may give directories to search for libraries to the compiler by means of --LL flags. Directories on the search path for a suffix which was the source of the ..LLIIBBSS target will be placed in the $$((..LLIIBBSS)) variable ready to be passed to the compiler. LLIIBBRRAARRIIEESS AANNDD AARRCCHHIIVVEESS Two other special forms of sources are recognized by _P_M_a_k_e. Any source that begins with the characters ``-l'' or ends in a suffix that is a source for the ..LLIIBBSS target is assumed to be a library, and any source that contains a left parenthesis in it is considered to be a member (or members) of an archive. Libraries are treated specially mostly in how they appear in the local variables of those targets that depend on them. If the system supports the --LL flag when linking, the name of the library (i.e. its ``-l'' form) is used in all local variables. _P_M_a_k_e assumes that you will use the $(.LIBS) variable in the appropriate place. If, however, the system does not have this feature, the name is expanded to its full pathname before it is placed in any local variable. One problem with libraries is they have a table of contents in them and when the file is touched (so the file's modifi- cation time and the time listed in the table of contents don't match), the library is declared to be ``out-of-date'' by the linker and the final linking stage of creating your program fails miserably. To avoid this problem, when you use the --tt flag, _P_M_a_k_e updates the time of the table of contents for the library, as well as the library itself. The process of creating a library or archive can be a pain- ful one, what with all the members having to be kept outside the archive as well as inside it in order to keep them from being recreated. _P_M_a_k_e has been set up, however, to allow you to reference files that are in an archive in a rela- tively painless manner. The specification of an archive member is written as: _a_r_c_h_i_v_e(_m_e_m_b_e_r [_m_e_m_b_e_r...]) Both the open and close parenthesis are required and there may be any number of members between them (except 0, that is). Members may also include wildcards characters. When such a source is examined, it is the modification time of the member, as recorded in the archive, that is used to determine its datedness. Sprite v.1.0 4 February 1991 22 PMAKE User Commands PMAKE If an archive member has no commands associated with it, _P_M_a_k_e goes through a special process to find commands for it. First, implicit sources are sought using the ``member'' portion of the specification. So if you have something like ``libcompat.a(procFork.o)'' for a target, _P_M_a_k_e attempts to find sources for the file ``procFork.o,'' even if it doesn't exist. If such sources exist, _P_M_a_k_e then looks for a transformation rule from the member's suffix to the archive's (in this case from .o -> .a) and tacks those com- mands on as well. To make these transformations easier to write, three local variables are defined for the target: .ARCHIVE (%) The path to the archive file. .MEMBER (!) The actual member name (literally the part in parentheses). @u-3p .TARGET (@) The path to the file which will be archived, if it is only a source, or the same as the ..MMEEMMBBEERR variable if it is also a target. Using the transformations already in the system makefile, a makefile for a library might look something like this: OBJS = procFork.o procExec.o procEnviron.o fsRead.o .o.a : ... rm -f $(.MEMBER) lib.a : lib.a($(OBJS)) ar cru $(.TARGET) $(.OODATE) ranlib $(.TARGET) You might be wondering, at this point, why I did not define the .o -> .a transformation like this: .o.a : ar r $(.ARCHIVE) $(.TARGET) ... rm -f $(.TARGET) The reason is simple: you cannot execute ``ar'' on the same file several times at once. If you try, you end up with a corrupted archive. So rather than reduce _P_M_a_k_e to executing only one job at a time, I chose to archive all the out-of- date files at once (this turns out to be faster anyway). OOUUTTPPUUTT When creating targets in parallel, several shells are exe- cuting at once, each wanting to write its own two cent's Sprite v.1.0 4 February 1991 23 PMAKE User Commands PMAKE worth onto the screen. This output must be captured by _P_M_a_k_e in some way in order to prevent the screen from being filled with garbage even more indecipherable than one can already get from these programs. _P_M_a_k_e has two ways of doing this, one of which provides for much cleaner output and a clear delineation between the output of different jobs, the other of which provides a more immediate response so one can tell what is really happening. The former is done by notifying the user when the creation of a given tar- get starts, capturing the output, and transferring it to the screen when the job finishes, preceded by an indication as to which job produced the output. The latter is done by catching the output of the shell (and its children) and buffering it until an entire line is received, then printing that line preceded by the name of the job from which the line came. The name of the job is just the target which is being created by it. Since I prefer this second method, it is the one used by default. The first method will be used if the --PP flag is given to _P_M_a_k_e. PPAARRAALLLLEELLIISSMM As mentioned before, _P_M_a_k_e attempts to create several tar- gets at once. On some systems where load balancing or pro- cess migration is in effect, the amount of concurrency which can be used will be much greater than on others. During the development of _P_M_a_k_e, I found that while one could create up to five targets at once on a Sun 3 without making the machine unusable, attempting the same feat on a Sun 2 would grind the machine into the dirt, most likely making the whole process run slower than it would have under _M_a_k_e. In addition, the use of _P_M_a_k_e on a multi-user machine (in con- trast to a workstation) calls for judicious use of con- currency to avoid annoying the other users. The ability to execute tasks in parallel, in combination with the execution of only one shell per target, brings about decreases in creation time on the order of 25%-60%. The --JJ and --LL flags are used to control the number of shells executing at once and should be used to find the best level for your machine. Once this is found, the default level can be set at that point and _P_M_a_k_e recompiled. BBAACCKKWWAARRDD--CCOOMMPPAATTIIBBIILLIITTYY _P_M_a_k_e was designed to be as backwards-compatible with _M_a_k_e as possible. In spite of this, however, there are a few major differences which may cause problems when using old makefiles: 1) The variable substitution, as mentioned earlier, is very different and will cause problems unless the makefile is converted or the --VV flag is given. Sprite v.1.0 4 February 1991 24 PMAKE User Commands PMAKE 2) Because targets are created in parallel, certain sequences which depend on the sources of a target being created sequentially will fail miserably. E.g.: prod : $(PROGRAM) clean This is liable to cause some of the object files to be removed after having been created during the current invocation (or, at the very least, the object files will not be removed when the program has been made), leading to errors in the final linking stage. This problem cannot even be gotten around by limiting the maximum concurrency to one, since the traversal of the dependency graph is done in a breadth-first, rather than a depth-first way. This can only be gotten around by rewriting the makefile, or by invoking _P_M_a_k_e with the --MM flag. One other possible conflict arises because _P_M_a_k_e forks only one shell to execute the commands to re-create a target. This means that changes of directory, environment, etc., remain in effect throughout the creation process. It also allows for a more natural entry of shell constructs, such as the ``for'' and ``while'' loops in the Bourne shell, without the need for backslashes and semi-colons required by the one-shell-per-command paradigm used by _M_a_k_e. This shouldn't pose any serious difficulties (or even any trivial ones so far as I can see), but should, in fact, make life a little easier. It is, however, possible to have _P_M_a_k_e execute each command in a single shell by giving it the --BB flag. FFIILLEESS Makefile or makefile default input file /sprite/lib/pmake/sys.mk System makefile (the built-in rules) EENNVVIIRROONNMMEENNTT PPMMAAKKEE Flags PMake should always use when invoked. SSEEEE AALLSSOO _m_a_k_e(1) for a more complete explanation of the lower-case flags to _P_M_a_k_e. KKEEYYWWOORRDDSS make, transformation AAUUTTHHOORR Adam de Boor Sprite v.1.0 4 February 1991 25